GitLab CI 語法與變數整理

TLDR

• GitLab CI 設定檔為 .gitlab-ci.yml，建議使用 rules 取代舊版的 only/except 以獲得更佳的靈活性。
• 變數引用建議使用 ${VARIABLE_NAME} 語法，以確保與前後文字連接時解析正確。
• workflow:rules 可全域控制 Pipeline 是否執行，若所有規則評估為 when:never，則整個 Pipeline 不會觸發。
• needs 關鍵字可打破 Stage 順序限制，讓 Job 在指定依賴完成後立即執行。
• 使用 YAML 錨點（& 與 *）可建立可重複使用的 Job 模板，減少重複設定。

基本結構與 Stages

GitLab CI 的核心設定檔為 .gitlab-ci.yml。透過 stages 定義執行順序，同一個 stage 中的 jobs 會並行執行，且必須全部成功後才會進入下一個階段。

stages:
  - build
  - test
  - deploy

Rules 與 Only/Except 的選擇

什麼情況下會遇到這個問題：當需要根據分支、標籤或觸發來源精確控制 Job 執行時。

GitLab 官方已不建議使用 only/except，改為推薦使用 rules。rules 支援更複雜的邏輯判斷，且規則會按順序評估。

# 推薦寫法
deploy-job:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - if: $CI_COMMIT_TAG
      when: always
    - when: never

變數引用注意事項

什麼情況下會遇到這個問題：當變數名稱緊鄰其他字元，導致 Shell 解析錯誤時。

在 GitLab CI 中，建議一律使用 ${VARIABLE_NAME} 語法來引用變數，這能明確界定變數名稱範圍，避免解析衝突。

Workflow：全域 Pipeline 控制

workflow:rules 用於決定是否建立整個 Pipeline，這與 Job 層級的 rules 不同。

TIP

若沒有設定 workflow:rules，GitLab 會使用預設規則（所有 push 和合併請求都會觸發）。若設定了規則但全部匹配到 when:never，則 Pipeline 將完全不執行。

實用範例：根據提交訊息控制

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /\[skip ci\]/
      when: never
    - if: $CI_COMMIT_TITLE =~ /\[run ci\]/
      when: always
    - when: on_success

效能優化：Needs 與 Cache

• Needs: 允許 Job 在依賴的特定 Job 完成後立即執行，無需等待整個 Stage 結束。
• Cache: 用於儲存跨 Pipeline 的檔案（如 node_modules/），建議使用 ${CI_COMMIT_REF_SLUG} 作為 key 以區隔不同分支。

模板化設定

使用 YAML 錨點（Anchors）可以避免重複定義相同的設定：

.build_template: &build_definition
  stage: build
  script:
    - echo "Building..."

build_job1:
  <<: *build_definition
  script:
    - make build

預先定義環境變數參考

GitLab 提供豐富的預定義變數，以下列出開發者最常使用的類別：

• 提交相關: CI_COMMIT_SHA (提交版本)、CI_COMMIT_REF_NAME (分支或標籤名稱)、CI_COMMIT_SHORT_SHA (短版 SHA)。
• 專案相關: CI_PROJECT_ID、CI_PROJECT_URL、CI_PROJECT_PATH。
• Job 相關: CI_JOB_ID、CI_JOB_NAME、CI_JOB_URL。
• 合併請求相關: CI_MERGE_REQUEST_IID、CI_MERGE_REQUEST_SOURCE_BRANCH_NAME。

詳細變數清單請參考 GitLab 官方文件。

異動歷程

• 2025-04-07 初版文件建立。